Skip to content

BLS-ISP/NextPolicyAgent

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

15 Commits
.github/workflows
.github/workflows
 
 
Documentation
Documentation
 
 
examples
examples
 
 
npa
npa
 
 
.dockerignore
.dockerignore
 
 
.gitignore
.gitignore
 
 
Dockerfile
Dockerfile
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
benchmark.py
benchmark.py
 
 
benchmark_results.json
benchmark_results.json
 
 
docker-compose.yml
docker-compose.yml
 
 
npa.ini
npa.ini
 
 
pyproject.toml
pyproject.toml
 
 
requirements.txt
requirements.txt
 
 
start-npa.ps1
start-npa.ps1
 
 
start-npa.sh
start-npa.sh
 
 
stop-npa.ps1
stop-npa.ps1
 
 
stop-npa.sh
stop-npa.sh
 
 
test_evaluator.py
test_evaluator.py
 
 
test_formatter.py
test_formatter.py
 
 
test_new_features.py
test_new_features.py
 
 
test_parser.py
test_parser.py
 
 
test_phase8_features.py
test_phase8_features.py
 
 

Repository files navigation

Next Policy Agent (NPA)

High-performance, secure policy engine — Python/FastAPI rewrite of Open Policy Agent (OPA)

PyPI Python License OPA Compatible Docker CVE-Free pip-audit

Features

  • Rego-kompatible Policy-Sprache — optimierter Parser und Evaluator, Rego v1 Syntax
  • HTTPS by Default — TLS 1.2+ als Standard, automatische Zertifikatsgenerierung
  • OPA-kompatible REST-API — Drop-in-Replacement für /v1/data, /v1/policies, /v1/query
  • Docker-Ready — Fedora 41 basiertes Container-Image (~300 MB)
  • Web-Dashboard — integrierte Verwaltungsoberfläche mit Live-Metriken
  • Async-First Architecture — FastAPI + uvicorn für maximale Performance
  • Multi-Layer Caching — BaseCache, InterQueryCache, PreparedQueryCache
  • Modulares Plugin-System — Bundles, Decision Logs, Status, Discovery
  • Dual Storage — In-Memory (Default) + SQLite (Persistenz)
  • Bundle-System — Signierung (JWT), Delta-Updates, OCI-Registry
  • Vollständige Observability — OpenTelemetry, Prometheus, Structured Logging
  • Modern CLI — Typer-basiert mit Rich-Output
  • Embeddable SDK — NPA als Library in Python-Anwendungen einbetten

Schnellstart

Installation via PyPI

pip install nextpolicyagent

# Server starten
npa run

Installation aus dem Repository (Entwicklung)

git clone https://github.com/BLS-ISP/NextPolicyAgent.git
cd NextPolicyAgent

# venv erstellen und aktivieren
python -m venv .venv
.venv\Scripts\activate      # Windows (PowerShell)
source .venv/bin/activate    # Linux/macOS

# Dependencies installieren
pip install -e ".[dev]"

# Server starten (HTTPS mit Auto-TLS)
npa run

# Mit eigenem Zertifikat
npa run --addr 0.0.0.0:8443 --tls-cert-file cert.pem --tls-private-key-file key.pem

# Ohne TLS (nur Entwicklung)
npa run --no-tls

Hinweis: Die Start-Skripte (start-npa.ps1 / start-npa.sh) erkennen das .venv automatisch.

Docker

# Image bauen und starten
docker build -t npa:latest .
docker run -d -p 8443:8443 --name npa npa:latest

# Oder mit Docker Compose
docker compose up -d

Policy evaluieren

# Über CLI
npa eval "data.authz.allow" --input input.json --data policy.rego

# Über REST-API
curl -sk -X POST https://localhost:8443/v1/data/authz/allow \
  -H "Content-Type: application/json" \
  -d '{"input": {"role": "admin"}}'

Weitere CLI-Befehle

npa test ./policies/     # Tests ausführen
npa fmt ./policies/      # Code formatieren
npa check policy.rego    # Syntax prüfen
npa parse policy.rego    # AST anzeigen
npa build -b bundle/     # Bundle erstellen
npa sign bundle.tar.gz   # Bundle signieren
npa version              # Version anzeigen

Docker

NPA läuft als Docker-Container auf Basis von Fedora 41 (~300 MB Image).

# Schnellstart
docker build -t npa:latest .
docker run -d -p 8443:8443 npa:latest

# Mit Policies und Daten
docker run -d -p 8443:8443 \
  -v ./policies:/policies:ro \
  -v ./data:/data:ro \
  npa:latest

# Health-Check
curl -sk https://localhost:8443/health

Vollständige Anleitung: Documentation/Docker-Anleitung.md

Docker Compose

docker compose up -d          # Starten
docker compose up -d --build  # Neu bauen + starten
docker compose logs -f npa    # Logs verfolgen
docker compose down           # Stoppen

REST-API (OPA-kompatibel)

NPA implementiert die OPA REST-API für direkten Austausch:

Endpoint Methode Beschreibung
/v1/data/{path} GET, POST Daten abfragen / Policy evaluieren
/v1/data/{path} PUT, PATCH, DELETE Daten verwalten
/v1/policies/{id} GET, PUT, DELETE Policies verwalten
/v1/policies GET Alle Policies auflisten
/v1/query POST Ad-hoc Rego-Query ausführen
/v1/compile POST Partial Evaluation
/health GET Health-Check
/ GET Web-Dashboard

Beispiele

# Policy hochladen
curl -sk -X PUT https://localhost:8443/v1/policies/authz \
  -H "Content-Type: text/plain" \
  -d 'package authz
default allow = false
allow if { input.role == "admin" }'

# Policy evaluieren
curl -sk -X POST https://localhost:8443/v1/data/authz/allow \
  -H "Content-Type: application/json" \
  -d '{"input": {"role": "admin"}}'
# → {"result": true}

# Daten setzen
curl -sk -X PUT https://localhost:8443/v1/data/users \
  -H "Content-Type: application/json" \
  -d '{"admins": ["alice", "bob"]}'

# Alle Policies auflisten
curl -sk https://localhost:8443/v1/policies

Konfiguration

Alle Einstellungen über Umgebungsvariablen (Prefix NPA_), Config-Datei (YAML/JSON) oder CLI-Flags.

Bereich Variablen Beschreibung
Server NPA_SERVER_ADDR, NPA_SERVER_PORT Bind-Adresse/Port (Default: 0.0.0.0:8443)
TLS NPA_TLS_ENABLED, NPA_TLS_CERT_FILE, NPA_TLS_KEY_FILE HTTPS-Konfiguration
Auth NPA_AUTH_ENABLED, NPA_AUTH_JWT_SECRET, NPA_AUTH_UI_PASSWORD Authentifizierung
Logging NPA_LOGGING_LEVEL, NPA_LOG_FORMAT Log-Level und Format
Storage NPA_STORAGE_BACKEND, NPA_STORAGE_DISK_PATH Backend-Auswahl

Vollständige Referenz: Documentation/Docker-Anleitung.md – Konfiguration

Policy-Beispiele

6 praxisnahe, OPA-verifizierte Rego-Policies unter examples/:

Beispiel Package Beschreibung
rbac/ rbac.authz Rollenbasierte Zugriffskontrolle
http-api-authz/ httpapi.authz REST-API Endpunktschutz
kubernetes-admission/ kubernetes.admission K8s Pod-Validierung
network-firewall/ network.firewall IP/Port Firewall-Regeln
jwt-validation/ jwt.validation JWT Token-Prüfung
data-filtering/ filtering Daten-Filterung & Aggregation

Alle Beispiele sind mit opa check validiert und liefern identische Ergebnisse in NPA und OPA.

# Beispiel lokal
npa eval -d examples/rbac/ -i examples/rbac/input.json "data.rbac.authz"

# Beispiel im Docker-Container
docker exec -it npa python3 -m npa eval \
  -d /examples/rbac/ -i /examples/rbac/input.json "data.rbac.authz"

Detaillierte Beschreibung: examples/README.md

Plugin-Beispiele

5 Beispiele unter examples/plugins/ demonstrieren das NPA-Plugin-System:

Beispiel Beschreibung
audit_trail_plugin.py Lokales JSONL Audit-Logging mit Rotation
rate_limit_plugin.py Sliding-Window Rate-Limiting pro Client
webhook_notification_plugin.py Webhook-Alerts (Slack, Teams, Generic JSON)
metrics_plugin.py Prometheus-kompatible Metriken-Sammlung
builtin_config_plugin.py Konfiguration der 4 Built-in Plugins + YAML-Template 
# Plugin-Beispiel ausführen
python -m examples.plugins.audit_trail_plugin
python -m examples.plugins.rate_limit_plugin
python -m examples.plugins.metrics_plugin

Detaillierte Beschreibung: examples/plugins/README.md

Architektur

┌──────────────────────────────────────────────────────┐
│                    CLI (Typer)                        │
├──────────────────────────────────────────────────────┤
│              FastAPI Server (HTTPS)                   │
│  ┌──────┐ ┌───────┐ ┌────────┐ ┌─────────────────┐  │
│  │ Data │ │ Query │ │ Policy │ │ Health/Metrics   │  │
│  └──────┘ └───────┘ └────────┘ └─────────────────┘  │
├──────────────────────────────────────────────────────┤
│             Web-Dashboard (HTML/JS)                   │
├──────────────────────────────────────────────────────┤
│                 Plugin Manager                        │
│  ┌────────┐ ┌──────┐ ┌────────┐ ┌───────────────┐   │
│  │ Bundle │ │ Logs │ │ Status │ │   Discovery   │   │
│  └────────┘ └──────┘ └────────┘ └───────────────┘   │
├──────────────────────────────────────────────────────┤
│                  Rego Engine                          │
│  ┌────────┐ ┌──────────┐ ┌────────┐ ┌───────────┐   │
│  │ Parser │→│ Compiler │→│TypeChk │→│ Evaluator │   │
│  └────────┘ └──────────┘ └────────┘ └───────────┘   │
├──────────────────────────────────────────────────────┤
│   Storage (Memory/SQLite)  │   Cache (Multi-Layer)   │
└──────────────────────────────────────────────────────┘

Verbesserungen gegenüber OPA

Bereich OPA NPA
HTTPS Optional Default (Auto-TLS)
Container Scratch (Go binary) Fedora 41 (~300 MB)
Storage BadgerDB (instabil) SQLite (bewährt)
I/O Synchron (Go) Async (asyncio)
Serialisierung encoding/json orjson (10x schneller)
CLI cobra Typer + Rich
Logging logrus structlog
Config Validation Manuell Pydantic
Rate Limiting Keins Eingebaut
Web UI Basic Status Dashboard mit Live-Metriken

Sicherheit & CVE-Status

NPA wird regelmäßig mit pip-audit gegen die OSV-Datenbank auf bekannte Sicherheitslücken geprüft.

Letzter Scan (März 2026)

Metrik Ergebnis
Direkte Abhängigkeiten 19 Pakete
Transitive Abhängigkeiten 40 Pakete (gesamt)
Bekannte CVEs 0 kritisch, 0 hoch
Status ✅ Keine ausnutzbaren Schwachstellen
Details zum Scan-Ergebnis

Alle direkten Abhängigkeiten sind CVE-frei:

Paket Version Status
FastAPI 0.135.1 ✅ Clean
uvicorn 0.41.0 ✅ Clean
cryptography ≥46.0.6 ✅ Clean
PyJWT 2.12.0 ✅ Clean
pydantic 2.12.5 ✅ Clean
httpx 0.28.1 ✅ Clean
orjson 3.11.7 ✅ Clean
aiosqlite 0.22.1 ✅ Clean
structlog 25.5.0 ✅ Clean
OpenTelemetry 1.40.0 ✅ Clean
Starlette 1.0.0 ✅ Clean

Hinweis: Pygments (transitive Dep via Rich, CLI-Output) hat einen offenen Low-Severity-CVE (CVE-2026-4539, lokaler ReDoS im AdlLexer). Dieser Lexer wird von NPA nicht verwendet und ist nur mit lokalem Zugriff ausnutzbar.

Scan reproduzieren:

pip install pip-audit
pip-audit -r <(pip freeze | grep -E "fastapi|uvicorn|orjson|cryptography|PyJWT|pydantic|httpx|aiosqlite|typer|rich|structlog|prometheus|opentelemetry|cachetools|xxhash|psutil|pyyaml")

Sicherheitsmaßnahmen

  • HTTPS by Default — TLS 1.2+ mit automatischer Zertifikatsgenerierung
  • Dependency Pinning — Alle Abhängigkeiten mit Mindestversionen gesichert
  • Regelmäßige CVE-Scans — Automatisierte Prüfung gegen OSV-Datenbank
  • Kein C-Code — Pure Python, keine nativen Exploits durch Buffer Overflows
  • Pydantic Validation — Strikte Input-Validierung auf allen API-Endpunkten
  • JWT Authentication — Optionale API-Absicherung mit Token-basierter Auth
  • Rate Limiting — Eingebauter Schutz gegen Brute-Force und DoS

Projektstruktur

NextPolicyAgent/
├── Dockerfile                    # Multi-Stage Fedora 41 Build
├── docker-compose.yml            # Docker Compose Konfiguration
├── .dockerignore                 # Docker Build-Ausschlüsse
├── pyproject.toml                # Python-Projektdefinition
├── start-npa.ps1 / .sh          # Start-Skripte (Windows/Linux)
├── stop-npa.ps1                  # Stop-Skript (Windows)
├── examples/                     # 6 Policy-Beispiele + 5 Plugin-Beispiele
├── Documentation/                # Anleitungen
│   └── Docker-Anleitung.md      # Vollständige Docker-Anleitung
└── npa/                          # Quellcode
    ├── __init__.py               # Version (1.0.0)
    ├── ast/
    │   ├── types.py              # AST-Knotentypen (frozen dataclasses)
    │   ├── lexer.py              # Rego Tokenizer
    │   ├── parser.py             # Recursive-Descent Parser (Rego v1)
    │   ├── compiler.py           # RuleTree/ModuleTree Compiler
    │   └── builtins.py           # 100+ Built-in-Funktionen
    ├── eval/
    │   ├── topdown.py            # Top-Down Evaluator mit Backtracking
    │   ├── cache.py              # Intra-Query + Inter-Query Cache (LRU/TTL)
    │   ├── partial.py            # Partial Evaluation
    │   └── unify.py              # Unification Engine
    ├── server/
    │   ├── app.py                # FastAPI App Factory (HTTPS-first)
    │   ├── auth.py               # JWT/API-Key Auth Middleware
    │   ├── static/               # Web-Dashboard (HTML/CSS/JS)
    │   └── routes/
    │       ├── data.py           # /v1/data/* (GET/POST/PUT/PATCH/DELETE)
    │       ├── policy.py         # /v1/policies/* (CRUD)
    │       ├── query.py          # /v1/query + /v1/compile
    │       └── health.py         # /health, /health/live, /health/ready
    ├── storage/
    │   ├── base.py               # Abstract Storage + Transaction Interface
    │   ├── inmemory.py           # Thread-safe In-Memory Store
    │   └── disk.py               # SQLite-backed Persistent Store (WAL)
    ├── bundle/
    │   ├── bundle.py             # Bundle Format (.tar.gz), Load/Build
    │   ├── sign.py               # JWT-basierte Bundle-Signierung
    │   └── loader.py             # Async HTTP/Disk Loader mit Polling
    ├── plugins/
    │   └── manager.py            # Plugin Lifecycle + Bundle/Log/Status Plugins
    ├── format/
    │   └── formatter.py          # Rego Code Formatter
    ├── config/
    │   └── config.py             # Pydantic Settings (TLS, Server, Auth, ...)
    ├── sdk/
    │   └── sdk.py                # Embeddable SDK (NPA Klasse)
    └── cli/
        └── main.py               # Typer CLI (run/eval/build/check/parse/sign/inspect)

SDK-Nutzung (Embedded)

NPA kann als Library direkt in Python-Anwendungen eingebettet werden:

from npa.sdk.sdk import NPA

engine = NPA()
engine.load_policy("authz.rego", """
    package authz
    default allow = false
    allow if { input.role == "admin" }
""")

result = engine.decide_bool("data.authz.allow", {"role": "admin"})
# True

result = engine.decide("data.authz", {"role": "admin"})
# {"result": [{"allow": True, ...}]}

Dokumentation

Einstieg

Dokument Beschreibung
Schnellstart In 10 Minuten von Installation bis erste Policy
Web-Dashboard Benutzerhandbuch für das integrierte Web-UI (7 Seiten)
CLI-Referenz Alle 13 Kommandozeilen-Befehle im Detail
REST-API-Referenz Vollständige HTTP-Endpunkt-Dokumentation
Rego-Sprachreferenz Rego-Syntax und 192+ Built-in Funktionen
SDK-Referenz Python SDK zum Einbetten in eigene Apps
Konfigurationsreferenz Alle Config-Optionen mit Umgebungsvariablen

Beispiele & Betrieb

Dokument Beschreibung
Docker-Anleitung Container-Setup, Konfiguration, Produktion
Policy-Beispiele 6 praxisnahe Rego-Policies mit Erklärung
Plugin-Beispiele 5 Plugin-Beispiele mit Architektur-Übersicht
Performance-Vergleich Benchmark OPA vs. NPA (8 Tests)

Hintergrund

Dokument Beschreibung
OPA Gap-Analyse Kompatibilitätsvergleich NPA vs. OPA
Anforderungsprofil Ursprüngliche Analyse und Designziele

Lizenz

Dieses Projekt steht unter der GNU General Public License v3.0 (GPL-3.0).
Siehe LICENSE für den vollständigen Lizenztext.

About

An OPA Clone in Python with some extra Features

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages